vite-plugin-dts

What is vite-plugin-dts?

vite-plugin-dts is a Vite plugin that generates TypeScript declaration files (d.ts) for your project. It helps in ensuring type safety and better developer experience by providing type definitions for your code.

What are vite-plugin-dts's main functionalities?

Generate TypeScript Declarations

This feature allows you to automatically generate TypeScript declaration files for your project. By including the plugin in your Vite configuration, it will generate .d.ts files for your TypeScript code.

import dts from 'vite-plugin-dts';

export default {
  plugins: [dts()]
};

Custom Output Directory

You can specify a custom output directory for the generated declaration files. This is useful if you want to organize your type definitions in a specific folder.

import dts from 'vite-plugin-dts';

export default {
  plugins: [
    dts({
      outputDir: 'types'
    })
  ]
};

Include/Exclude Specific Files

This feature allows you to include or exclude specific files or folders from the declaration generation process. You can use glob patterns to specify the files to include or exclude.

import dts from 'vite-plugin-dts';

export default {
  plugins: [
    dts({
      include: ['src/**/*.ts'],
      exclude: ['src/excluded-folder/**']
    })
  ]
};

Other packages similar to vite-plugin-dts

tsc

The TypeScript compiler (tsc) can be used to generate declaration files. It is a more general tool compared to vite-plugin-dts and can be used in any TypeScript project, not just those using Vite. However, it requires more configuration and does not integrate as seamlessly with Vite.

rollup-plugin-dts

rollup-plugin-dts is a Rollup plugin that generates TypeScript declaration files. It is similar to vite-plugin-dts but is designed for use with Rollup instead of Vite. If you are using Rollup as your bundler, this plugin would be a better fit.

README

vite-plugin-dts

A vite plugin that generates declaration files (*.d.ts) from .ts(x) or .vue source files when using vite in library mode.

English | 中文

Notice: skipDiagnostics option default to false since 1.7.0.

Install

pnpm add vite-plugin-dts -D

Usage

In vite.config.ts:

import { resolve } from 'path'
import { defineConfig } from 'vite'
import dts from 'vite-plugin-dts'

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      formats: ['es'],
      fileName: 'my-lib'
    }
  },
  plugins: [dts()]
})

In your component:

<template>
  <div></div>
</template>

<script lang="ts">
// using defineComponent for inferring types
import { defineComponent } from 'vue'

export default defineComponent({
  name: 'Component'
})
</script>

<script setup lang="ts">
// Need to access the defineProps returned value to
// infer types although you never use the props directly
const props = defineProps<{
  color: 'blue' | 'red'
}>()
</script>

<template>
  <div>{{ color }}</div>
</template>

FAQ

Here are some FAQ's and solutions.

Missing some declaration files after build (before 1.7.0)

By default skipDiagnostics option is true, which means that type diagnostic will be skipped during the build process (some projects may have diagnostic tools such as vue-tsc). If there are some files with type errors which interrupt the build process, these files will not be emitted (declaration files won't be generated).

If your project doesn't use type diagnostic tools, you can set skipDiagnostics: false and logDiagnostics: true to turn on the diagnostic and log features of this plugin. It will help you check the type errors during build and log error information to the terminal.

Take type error when using both script and setup-script in vue component

This is usually caused by using defineComponent function in both script and setup-script. When vue/compiler-sfc compiles these files, the default export result from script gets merged with the parameter object of defineComponent from setup-script. This is incompatible with parameters and types returned from defineComponent, which results in a type error.

Here is a simple example, you should remove the defineComponent which in script and export a native object directly.

Take errors that unable to infer types from packages which under node_modules

This is a exist issue when TypeScript inferring types from packages which under node_modules through soft links (pnpm), you can refer to this issue. Currently has a workaround that add baseUrl to your tsconfig.json and specify the paths for these packages:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "third-lib": ["node_modules/third-lib"]
    }
  }
}

Options

import type { ts, Diagnostic } from 'ts-morph'

interface TransformWriteFile {
  filePath?: string
  content?: string
}

export interface PluginOptions {
  /**
   * Depends on the root directory
   *
   * Defaults base on your vite config root options
   */
  root?: string

  /**
   * Declaration files output directory
   *
   * Can be specified a array to output to multiple directories
   *
   * Defaults base on your vite config output options
   */
  outputDir?: string | string[]

  /**
   * Manually set the root path of the entry files
   *
   * The output path of each file will be caculated base on it
   *
   * Defaults is the smallest public path for all files
   */
  entryRoot?: string

  /**
   * Project init compilerOptions using by ts-morph
   *
   * @default null
   */
  compilerOptions?: ts.CompilerOptions | null

  /**
   * Project init tsconfig.json file path by ts-morph
   *
   * Plugin also resolve incldue and exclude files from tsconfig.json
   *
   * @default 'tsconfig.json'
   */
  tsConfigFilePath?: string

  /**
   * Set which paths should exclude when transform aliases
   *
   * If it's regexp, it will test the original import path directly
   *
   * @default []
   */
  aliasesExclude?: (string | RegExp)[]

  /**
   * Whether transform file name '.vue.d.ts' to '.d.ts'
   *
   * @default false
   */
  cleanVueFileName?: boolean

  /**
   * Whether transform dynamic import to static
   *
   * Force true when `rollupTypes` is effective
   *
   * eg. 'import('vue').DefineComponent' to 'import { DefineComponent } from "vue"'
   *
   * @default false
   */
  staticImport?: boolean

  /**
   * Manual set include glob
   *
   * Defaults base on your tsconfig.json include option
   */
  include?: string | string[]

  /**
   * Manual set exclude glob
   *
   * Defaults base on your tsconfig.json exclude option, be 'node_modules/**' when empty
   */
  exclude?: string | string[]

  /**
   * Do not emit if content of file only includes 'export {}'
   *
   * @default true
   */
  clearPureImport?: boolean

  /**
   * Whether generate types entry file
   *
   * When true will from package.json types field if exists or `${outputDir}/index.d.ts`
   *
   * Force true when `rollupTypes` is effective
   *
   * @default false
   */
  insertTypesEntry?: boolean

  /**
   * Set to rollup declaration files after emit
   *
   * Power by `@microsoft/api-extractor`, it will start a new program which takes some time
   *
   * @default false
   */
  rollupTypes?: boolean

  /**
   * Whether copy .d.ts source files into outputDir
   *
   * @default true
   */
  copyDtsFiles?: boolean

  /**
   * Whether emit nothing when has any diagnostic
   *
   * @default false
   */
  noEmitOnError?: boolean

  /**
   * Whether skip typescript diagnostics
   *
   * Skip type diagnostics means that type errors will not interrupt the build process
   *
   * But for the source files with type errors will not be emitted
   *
   * @default false
   */
  skipDiagnostics?: boolean

  /**
   * Whether log diagnostic informations
   *
   * Not effective when `skipDiagnostics` is true
   *
   * @deprecated
   * @default false
   */
  logDiagnostics?: boolean

  /**
   * Customize typescript lib folder path
   *
   * Should pass a relative path to root or a absolute path
   *
   * @default undefined
   */
  libFolderPath?: string

  /**
   * After emit diagnostic hook
   *
   * According to the length to judge whether there is any type error
   *
   * @default () => {}
   */
  afterDiagnostic?: (diagnostics: Diagnostic[]) => void | Promise<void>

  /**
   * Before declaration file be writed hook
   *
   * You can transform declaration file-path and content through it
   *
   * The file will be skipped when return exact false
   *
   * @default () => {}
   */
  beforeWriteFile?: (filePath: string, content: string) => void | false | TransformWriteFile

  /**
   * After build hook
   *
   * It wil be called after all declaration files are written
   *
   * @default () => {}
   */
  afterBuild?: () => void | Promise<void>
}

Example

Clone and run the following script:

pnpm run test:ts

Then check examples/ts/types.

License

MIT License.

Changelog

1.7.3 (2023-02-14)

Bug Fixes

• incorrect compilerOptions when rollup dts (9dd8d9c), closes #171
• normalize mts and cts declaration files extension (410288a), closes #169